

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Getting started with Atoms &mdash; quippy 7ea04c5+ documentation</title>
  

  
  
    <link rel="shortcut icon" href="../_static/favicon.ico"/>
  
  
  

  
  <script type="text/javascript" src="../_static/js/modernizr.min.js"></script>
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
        <script type="text/javascript" src="../_static/jquery.js"></script>
        <script type="text/javascript" src="../_static/underscore.js"></script>
        <script type="text/javascript" src="../_static/doctools.js"></script>
        <script type="text/javascript" src="../_static/language_data.js"></script>
        <script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
        <script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "math|output_area", "processEscapes": true, "ignoreClass": "document", "inlineMath": [["$", "$"], ["\\(", "\\)"]]}})</script>
    
    <script type="text/javascript" src="../_static/js/theme.js"></script>

    

  
  <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../_static/theme_overrides.css" type="text/css" />
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Interoperability with Atomic Simulation Environment" href="quippy-ase-interoperability.html" />
    <link rel="prev" title="Tutorials" href="index.html" /> 
</head>

<body class="wy-body-for-nav">

   
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
          

          
            <a href="../index.html" class="icon icon-home"> quippy
          

          
            
            <img src="../_static/hybrid.png" class="logo" alt="Logo"/>
          
          </a>

          
            
            
              <div class="version">
                7ea04c5+
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
    
            
            
              
            
            
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../intro.html">Introduction to <code class="docutils literal notranslate"><span class="pre">quippy</span></code></a></li>
<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation of QUIP and quippy</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Tutorials</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Getting started with <code class="docutils literal notranslate"><span class="pre">Atoms</span></code></a><ul>
<li class="toctree-l3"><a class="reference internal" href="#ASE-and-quippy">ASE and <code class="docutils literal notranslate"><span class="pre">quippy</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#Useful-QUIP-equivalents">Useful QUIP equivalents</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#Changing-Atoms">Changing <code class="docutils literal notranslate"><span class="pre">Atoms</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#Generating-structures-from-scratch">Generating structures from scratch</a></li>
<li class="toctree-l3"><a class="reference internal" href="#Computing-the-energy">Computing the energy</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="quippy-ase-interoperability.html">Interoperability with Atomic Simulation Environment</a></li>
<li class="toctree-l2"><a class="reference internal" href="tutorial.html">Introductory Tutorial</a></li>
<li class="toctree-l2"><a class="reference internal" href="quippy-descriptor-tutorial.html">Using Quippy to compute descriptors of atomic environments</a></li>
<li class="toctree-l2"><a class="reference internal" href="adglass.html">Molecular Dynamics Simulation of Fracture in Quartz</a></li>
<li class="toctree-l2"><a class="reference internal" href="adaptive-qmmm.html">Adaptive QM/MM MD of Fracture in Silicon</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../quippy.html">Quippy library reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../visualisation.html">Visualisation Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fortran_wrapper.html">Appendix: wrapping Fortran 90 Code</a></li>
<li class="toctree-l1"><a class="reference internal" href="../teach_sparse.html">Command line options of the teach_sparse main program</a></li>
</ul>

            
          
    <p></p>
    <ul>
        <li><a href="../genindex.html">Index</a></li>
        <li><a href="../py-modindex.html">Module Index</a></li>
        <li><a href="../search.html">Search Page</a></li>
        <li><a href="../_modules/index.html">Module Source Code</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">quippy</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="../index.html">Docs</a> &raquo;</li>
        
          <li><a href="index.html">Tutorials</a> &raquo;</li>
        
      <li>Getting started with <code class="docutils literal notranslate"><span class="pre">Atoms</span></code></li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="../_sources/Tutorials/Introduction.ipynb.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  
<style>
/* CSS for nbsphinx extension */

/* remove conflicting styling from Sphinx themes */
div.nbinput,
div.nbinput div.prompt,
div.nbinput div.input_area,
div.nbinput div[class*=highlight],
div.nbinput div[class*=highlight] pre,
div.nboutput,
div.nbinput div.prompt,
div.nbinput div.output_area,
div.nboutput div[class*=highlight],
div.nboutput div[class*=highlight] pre {
    background: none;
    border: none;
    padding: 0 0;
    margin: 0;
    box-shadow: none;
}

/* avoid gaps between output lines */
div.nboutput div[class*=highlight] pre {
    line-height: normal;
}

/* input/output containers */
div.nbinput,
div.nboutput {
    display: -webkit-flex;
    display: flex;
    align-items: flex-start;
    margin: 0;
    width: 100%;
}
@media (max-width: 540px) {
    div.nbinput,
    div.nboutput {
        flex-direction: column;
    }
}

/* input container */
div.nbinput {
    padding-top: 5px;
}

/* last container */
div.nblast {
    padding-bottom: 5px;
}

/* input prompt */
div.nbinput div.prompt pre {
    color: #307FC1;
}

/* output prompt */
div.nboutput div.prompt pre {
    color: #BF5B3D;
}

/* all prompts */
div.nbinput div.prompt,
div.nboutput div.prompt {
    min-width: 5ex;
    padding-top: 0.4em;
    padding-right: 0.4em;
    text-align: right;
    flex: 0;
}
@media (max-width: 540px) {
    div.nbinput div.prompt,
    div.nboutput div.prompt {
        text-align: left;
        padding: 0.4em;
    }
    div.nboutput div.prompt.empty {
        padding: 0;
    }
}

/* disable scrollbars on prompts */
div.nbinput div.prompt pre,
div.nboutput div.prompt pre {
    overflow: hidden;
}

/* input/output area */
div.nbinput div.input_area,
div.nboutput div.output_area {
    padding: 0.4em;
    -webkit-flex: 1;
    flex: 1;
    overflow: auto;
}
@media (max-width: 540px) {
    div.nbinput div.input_area,
    div.nboutput div.output_area {
        width: 100%;
    }
}

/* input area */
div.nbinput div.input_area {
    border: 1px solid #e0e0e0;
    border-radius: 2px;
    background: #f5f5f5;
}

/* override MathJax center alignment in output cells */
div.nboutput div[class*=MathJax] {
    text-align: left !important;
}

/* override sphinx.ext.imgmath center alignment in output cells */
div.nboutput div.math p {
    text-align: left;
}

/* standard error */
div.nboutput div.output_area.stderr {
    background: #fdd;
}

/* ANSI colors */
.ansi-black-fg { color: #3E424D; }
.ansi-black-bg { background-color: #3E424D; }
.ansi-black-intense-fg { color: #282C36; }
.ansi-black-intense-bg { background-color: #282C36; }
.ansi-red-fg { color: #E75C58; }
.ansi-red-bg { background-color: #E75C58; }
.ansi-red-intense-fg { color: #B22B31; }
.ansi-red-intense-bg { background-color: #B22B31; }
.ansi-green-fg { color: #00A250; }
.ansi-green-bg { background-color: #00A250; }
.ansi-green-intense-fg { color: #007427; }
.ansi-green-intense-bg { background-color: #007427; }
.ansi-yellow-fg { color: #DDB62B; }
.ansi-yellow-bg { background-color: #DDB62B; }
.ansi-yellow-intense-fg { color: #B27D12; }
.ansi-yellow-intense-bg { background-color: #B27D12; }
.ansi-blue-fg { color: #208FFB; }
.ansi-blue-bg { background-color: #208FFB; }
.ansi-blue-intense-fg { color: #0065CA; }
.ansi-blue-intense-bg { background-color: #0065CA; }
.ansi-magenta-fg { color: #D160C4; }
.ansi-magenta-bg { background-color: #D160C4; }
.ansi-magenta-intense-fg { color: #A03196; }
.ansi-magenta-intense-bg { background-color: #A03196; }
.ansi-cyan-fg { color: #60C6C8; }
.ansi-cyan-bg { background-color: #60C6C8; }
.ansi-cyan-intense-fg { color: #258F8F; }
.ansi-cyan-intense-bg { background-color: #258F8F; }
.ansi-white-fg { color: #C5C1B4; }
.ansi-white-bg { background-color: #C5C1B4; }
.ansi-white-intense-fg { color: #A1A6B2; }
.ansi-white-intense-bg { background-color: #A1A6B2; }

.ansi-default-inverse-fg { color: #FFFFFF; }
.ansi-default-inverse-bg { background-color: #000000; }

.ansi-bold { font-weight: bold; }
.ansi-underline { text-decoration: underline; }

/* Some additional styling taken form the Jupyter notebook CSS */
div.rendered_html table {
  border: none;
  border-collapse: collapse;
  border-spacing: 0;
  color: black;
  font-size: 12px;
  table-layout: fixed;
}
div.rendered_html thead {
  border-bottom: 1px solid black;
  vertical-align: bottom;
}
div.rendered_html tr,
div.rendered_html th,
div.rendered_html td {
  text-align: right;
  vertical-align: middle;
  padding: 0.5em 0.5em;
  line-height: normal;
  white-space: normal;
  max-width: none;
  border: none;
}
div.rendered_html th {
  font-weight: bold;
}
div.rendered_html tbody tr:nth-child(odd) {
  background: #f5f5f5;
}
div.rendered_html tbody tr:hover {
  background: rgba(66, 165, 245, 0.2);
}

/* CSS overrides for sphinx_rtd_theme */

/* 24px margin */
.nbinput.nblast,
.nboutput.nblast {
    margin-bottom: 19px;  /* padding has already 5px */
}

/* ... except between code cells! */
.nblast + .nbinput {
    margin-top: -19px;
}

.admonition > p:before {
    margin-right: 4px;  /* make room for the exclamation icon */
}

/* Fix math alignment, see https://github.com/rtfd/sphinx_rtd_theme/pull/686 */
.math {
    text-align: unset;
}
</style>
<div class="section" id="Getting-started-with-Atoms">
<h1>Getting started with <code class="docutils literal notranslate"><span class="pre">Atoms</span></code><a class="headerlink" href="#Getting-started-with-Atoms" title="Permalink to this headline">¶</a></h1>
<p>This example will walk you through getting started with using <code class="docutils literal notranslate"><span class="pre">quippy</span></code> by playing with a small molecule. It complements the (older) <a class="reference external" href="http://libatoms.github.io/QUIP/tutorial.html">introductory tutorial</a> which is longer and goes more in depth, though it is recommended that new users start here first. This example is especially recommended for those who want to get going and working with <code class="docutils literal notranslate"><span class="pre">Atoms</span></code> as quickly as possible.</p>
<p>First, make sure you have QUIP and <code class="docutils literal notranslate"><span class="pre">quippy</span></code> properly installed. If you can run the cell below, then congratulations! If not, then see the <a class="reference external" href="http://libatoms.github.io/QUIP/install.html">Installation instructions</a>.</p>
<div class="nbinput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[1]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>

<span class="kn">import</span> <span class="nn">quippy</span>
<span class="kn">from</span> <span class="nn">quippy</span> <span class="kn">import</span> <span class="n">Atoms</span>
</pre></div>
</div>
</div>
<p>Remember, this is an interactive tutorial. You are encouraged to run the cells yourself and even try editing the code to see what else you can do!</p>
<p>Now let’s try getting our hands on an <code class="docutils literal notranslate"><span class="pre">Atoms</span></code> object; this object is required to do almost anything useful in <code class="docutils literal notranslate"><span class="pre">quippy</span></code>.</p>
<div class="nbinput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[2]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct</span> <span class="o">=</span> <span class="n">quippy</span><span class="o">.</span><span class="n">Atoms</span><span class="p">(</span><span class="s1">&#39;methane.xyz&#39;</span><span class="p">)</span>
</pre></div>
</div>
</div>
<p>OK, now what do we do with it? Let’s look at the Atoms source file and see what sort of information is encoded in it:</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[3]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="o">!</span>cat methane.xyz
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
5
cutoff=-1.00000000 nneightol=1.20000000 pbc=&#34;T T T&#34; Lattice=&#34;10.00000000       0.00000000       0.00000000       0.00000000      10.00000000       0.00000000       0.00000000       0.00000000      10.00000000&#34; Properties=species:S:1:pos:R:3:Z:I:1
C               0.00000000      0.00000000      0.00000000       6
H               0.00000000      0.00000000      1.07000000       1
H               0.62414000      0.79255000     -0.35666000       1
H              -0.99844000      0.14425000     -0.35667000       1
H               0.37430000     -0.93680000     -0.35667000       1
</pre></div></div>
</div>
<p>We have positions, atomic symbols, atomic numbers, and a unit cell. There’s also some other information in there that we don’t need right now. But let’s see how to access these properties from <code class="docutils literal notranslate"><span class="pre">quippy</span></code>:</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[4]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="k">print</span><span class="p">(</span><span class="s2">&quot;Positions:&quot;</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">struct</span><span class="o">.</span><span class="n">get_positions</span><span class="p">())</span>
<span class="k">print</span><span class="p">(</span><span class="s2">&quot;Unit cell:&quot;</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">struct</span><span class="o">.</span><span class="n">get_cell</span><span class="p">())</span>
<span class="k">print</span><span class="p">(</span><span class="s2">&quot;Atomic numbers:&quot;</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">struct</span><span class="o">.</span><span class="n">get_atomic_numbers</span><span class="p">())</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
Positions:
[[ 0.       0.       0.     ]
 [ 0.       0.       1.07   ]
 [ 0.62414  0.79255 -0.35666]
 [-0.99844  0.14425 -0.35667]
 [ 0.3743  -0.9368  -0.35667]]
Unit cell:
[[ 10.   0.   0.]
 [  0.  10.   0.]
 [  0.   0.  10.]]
Atomic numbers:
[6 1 1 1 1]
</pre></div></div>
</div>
<p>(Remember, units in quippy are always Ångstrøms and electronvolts: <a class="reference external" href="http://libatoms.github.io/QUIP/units.html">http://libatoms.github.io/QUIP/units.html</a>)</p>
<p>You might want get an idea of what this structure actually looks like. The native <code class="docutils literal notranslate"><span class="pre">xyz</span></code> format is supported by many open-source molecular viewers, like <a class="reference external" href="http://www.ks.uiuc.edu/Research/vmd/">VMD</a> and <a class="reference external" href="https://avogadro.cc/">Avogadro</a>. If you’ve gotten the <code class="docutils literal notranslate"><span class="pre">atomeye</span></code> module to work you can use that as well.</p>
<p>We’re still looking for a simple way to view molecular structures in the notebook environment; once we (the developers) get that working with quippy we’ll update this tutorial.</p>
<p>Let’s try another way to get information about the structure: This is a molecule, so we can check the bonds and angles.</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[5]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct</span><span class="o">.</span><span class="n">get_distance</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">mic</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[5]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>1.0700000000000001
</pre></div>
</div>
</div>
<p>OK, that’s a pretty reasonable C-H bond length in a methane molecule. What about the other ones?</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[6]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="p">[</span><span class="n">struct</span><span class="o">.</span><span class="n">get_distance</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">mic</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">5</span><span class="p">)]</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[6]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>[1.0700000000000001,
 1.0699965409757173,
 1.0700018621479124,
 1.0700038406005841]
</pre></div>
</div>
</div>
<p><em>(Oh, and in case you’re wondering about the ``mic=True`` part, that just means to use the minimum image convention. It’s only really relevant when we use periodic systems, but it’s included here for completeness.)</em></p>
<p>And how about an H-C-H angle?</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[7]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct</span><span class="o">.</span><span class="n">get_angle</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[7]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>109.47090748192832
</pre></div>
</div>
</div>
<p>which is the correct “tetrahedral angle” between the hydrogens in a methane molecule (it’s equal to <span class="math notranslate nohighlight">\(\arccos\left(-\frac{1}{3}\right)\)</span>).</p>
<p>Note that the atom indices in these functions are <em>zero_based</em>, meaning the first atom (here, the carbon) is referred to by the index 0.</p>
<div class="section" id="ASE-and-quippy">
<h2>ASE and <code class="docutils literal notranslate"><span class="pre">quippy</span></code><a class="headerlink" href="#ASE-and-quippy" title="Permalink to this headline">¶</a></h2>
<p>If you’ve read some of the documentation, you may be aware of the following alternative method for getting the distance between the two atoms:</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[8]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct</span><span class="o">.</span><span class="n">distance_min_image</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[8]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>0.0
</pre></div>
</div>
</div>
<p>DANGER WILL ROBINSON! As you may have noticed, this isn’t the correct bond distance. In some circumstances the code may even just crash. This is because the above function is derived from the underlying Fortran code, QUIP, rather than the <code class="docutils literal notranslate"><span class="pre">get_distance</span></code> function from before, which came from ASE. Fortran, unlike Python and C, starts counting from one instead of zero (cue the holy wars), so we just gave QUIP an atom index that doens’t even exist – and that can have unpredictable results. Now,
the QUIP-derived functions are often useful, but for now it’ll just be too confusing to keep this indexing distinction in our heads - let’s stick with ASE until we have good reason to do otherwise.</p>
<p>So how do we tell whether a function is derived from QUIP or from ASE? Well, let’s take a look at this function’s help message:</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[9]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">help</span><span class="p">(</span><span class="n">struct</span><span class="o">.</span><span class="n">distance_min_image</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
Help on method &lt;lambda&gt; in module quippy._atoms:

&lt;lambda&gt; lambda self, *args, **kwargs method of quippy.atoms.Atoms instance
    This interface calculates the distance between the nearest periodic images of two points (or atoms).
     Return minimum image distance between two atoms or positions.
     End points can be specified by any combination of atoms indices
     &#39;i&#39; and &#39;j&#39; and absolute coordinates &#39;u&#39; and &#39;w&#39;. If &#39;shift&#39; is
     present the periodic shift between the two atoms or points will
     be returned in it.

    Wrapper around Fortran interface ``distance_min_image`` containing multiple routines:

       .. function :: distance_min_image(v,w,[shift])

          :param v:
          :type v:  input rank-1 array(&#39;d&#39;) with bounds (3)
          :param w:
          :type w:  input rank-1 array(&#39;d&#39;) with bounds (3)
          :param shift:
          :type shift:  in/output rank-1 array(&#39;i&#39;) with bounds (3), optional

          :returns: **ret_distance8_vec_vec** --  float


          Routine is wrapper around Fortran routine ``distance8_vec_vec`` defined in file :git:`src/libAtoms/Atoms_types.f95`.

       .. function :: distance_min_image(i,j,[shift])

          :param i:
          :type i:  input int
          :param j:
          :type j:  input int
          :param shift:
          :type shift:  in/output rank-1 array(&#39;i&#39;) with bounds (3), optional

          :returns: **ret_distance8_atom_atom** --  float


          Routine is wrapper around Fortran routine ``distance8_atom_atom`` defined in file :git:`src/libAtoms/Atoms_types.f95`.

       .. function :: distance_min_image(i,v,[shift])

          :param i:
          :type i:  input int
          :param v:
          :type v:  input rank-1 array(&#39;d&#39;) with bounds (3)
          :param shift:
          :type shift:  in/output rank-1 array(&#39;i&#39;) with bounds (3), optional

          :returns: **ret_distance8_atom_vec** --  float


          Routine is wrapper around Fortran routine ``distance8_atom_vec`` defined in file :git:`src/libAtoms/Atoms_types.f95`.

       .. function :: distance_min_image(v,j,[shift])

          :param v:
          :type v:  input rank-1 array(&#39;d&#39;) with bounds (3)
          :param j:
          :type j:  input int
          :param shift:
          :type shift:  in/output rank-1 array(&#39;i&#39;) with bounds (3), optional

          :returns: **ret_distance8_vec_atom** --  float


          Routine is wrapper around Fortran routine ``distance8_vec_atom`` defined in file :git:`src/libAtoms/Atoms_types.f95`.

</pre></div></div>
</div>
<p>A bit confusing, yes, but take a look at the final line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Routine is wrapper around Fortran routine ``distance8_vec_atom`` defined in file :git:`src/libAtoms/Atoms_types.f95`.
</pre></div>
</div>
<p>It says this function is a <em>wrapper</em> around something in the Fortran code, which means it’s from QUIP and only works with <em>one-based</em> indices (i.e. to this function, the first atom has the index 1).</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[10]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct</span><span class="o">.</span><span class="n">distance_min_image</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[10]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>1.07
</pre></div>
</div>
</div>
<p>Whereas the ASE function has a different help string:</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[11]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">help</span><span class="p">(</span><span class="n">struct</span><span class="o">.</span><span class="n">get_distance</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
Help on method get_distance in module ase.atoms:

get_distance(self, a0, a1, mic=False, vector=False) method of quippy.atoms.Atoms instance
    Return distance between two atoms.

    Use mic=True to use the Minimum Image Convention.
    vector=True gives the distance vector (from a0 to a1).

</pre></div></div>
</div>
<p>See that part, ‘<code class="docutils literal notranslate"><span class="pre">in</span> <span class="pre">module</span> <span class="pre">ase.atoms</span></code>’? That means this function comes from ASE and works with zero-based indices.</p>
<p>You should <em>always</em> do this check before using any <code class="docutils literal notranslate"><span class="pre">Atoms</span></code> function you’re not yet familiar with.</p>
<div class="section" id="Useful-QUIP-equivalents">
<h3>Useful QUIP equivalents<a class="headerlink" href="#Useful-QUIP-equivalents" title="Permalink to this headline">¶</a></h3>
<p>Just in case you ever want to work with the Fortran QUIP routines, here are some equivalents of the queries we’ve seen above:</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[12]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="p">[</span><span class="n">struct</span><span class="o">.</span><span class="n">distance_min_image</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">i</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">6</span><span class="p">)]</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[12]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>[1.07, 1.0699965409757173, 1.0700018621479124, 1.070003840600584]
</pre></div>
</div>
</div>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[13]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="k">print</span><span class="p">(</span><span class="n">struct</span><span class="o">.</span><span class="n">cosine</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">))</span>
<span class="k">print</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">arccos</span><span class="p">(</span><span class="n">struct</span><span class="o">.</span><span class="n">cosine</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">))</span> <span class="o">*</span> <span class="mi">180</span> <span class="o">/</span> <span class="n">np</span><span class="o">.</span><span class="n">pi</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt empty docutils container">
</div>
<div class="output_area docutils container">
<div class="highlight"><pre>
-0.333328180365
109.470907482
</pre></div></div>
</div>
<p>Note that the <em>order</em> of the arguments in <code class="docutils literal notranslate"><span class="pre">Atoms.cosine</span></code> is different as well: The central atom index is now the first argument.</p>
<p>The properties can also be accessed as one-based arrays (called <code class="docutils literal notranslate"><span class="pre">FortranArray</span></code>s). Note that these are also the <em>transpose</em> of the ASE arrays, so the row and column indices are swapped.</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[14]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct</span><span class="o">.</span><span class="n">pos</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[14]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>FortranArray([[ 0.     ,  0.     ,  0.62414, -0.99844,  0.3743 ],
              [ 0.     ,  0.     ,  0.79255,  0.14425, -0.9368 ],
              [ 0.     ,  1.07   , -0.35666, -0.35667, -0.35667]])
</pre></div>
</div>
</div>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[15]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct</span><span class="o">.</span><span class="n">lattice</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[15]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>FortranArray([[ 10.,   0.,   0.],
              [  0.,  10.,   0.],
              [  0.,   0.,  10.]])
</pre></div>
</div>
</div>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[16]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct</span><span class="o">.</span><span class="n">Z</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[16]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>FortranArray([6, 1, 1, 1, 1], dtype=int32)
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="Changing-Atoms">
<h2>Changing <code class="docutils literal notranslate"><span class="pre">Atoms</span></code><a class="headerlink" href="#Changing-Atoms" title="Permalink to this headline">¶</a></h2>
<p>There’s a more complete tutorial on manipulating Atoms objects in ASE at <a class="reference external" href="https://wiki.fysik.dtu.dk/ase/tutorials/manipulating_atoms.html">the ASE website</a>; this is a shorter example just to get you started.</p>
<p>First, let’s try reorienting our methane molecule in space. The first hydrogen atom is already oriented along the Z axis; let’s try to rotate the molecule so that the second one points along the X axis.</p>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[17]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">r_h2</span> <span class="o">=</span> <span class="n">struct</span><span class="o">.</span><span class="n">get_distance</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">vector</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">r_h2</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="n">np</span><span class="o">.</span><span class="n">arccos</span><span class="p">(</span><span class="n">r_h2</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">/</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">norm</span><span class="p">(</span><span class="n">r_h2</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[17]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>0.90371859179284519
</pre></div>
</div>
</div>
<p>So we need to rotate it by about -0.9 radians about the Z axis.</p>
<p>But first, we want to keep the old methane molecule for comparison. Let’s copy it - note that this must be done <em>explicitly</em>; the Python assignment operator (<code class="docutils literal notranslate"><span class="pre">=</span></code>) only assigns a new <em>reference</em> to the underlying object! This can be one of the hardest things to understand for programmers coming from a different language, so make sure to read up on Python references and do some of their tutorials if you find this distinction confusing.</p>
<div class="nbinput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[18]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct_old</span> <span class="o">=</span> <span class="n">struct</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="nbinput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[19]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct</span><span class="o">.</span><span class="n">rotate</span><span class="p">([</span><span class="mf">0.0</span><span class="p">,</span> <span class="mf">0.0</span><span class="p">,</span> <span class="mf">1.0</span><span class="p">],</span> <span class="o">-</span><span class="mf">1.0</span> <span class="o">*</span> <span class="n">np</span><span class="o">.</span><span class="n">arccos</span><span class="p">(</span><span class="n">r_h2</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">/</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">norm</span><span class="p">(</span><span class="n">r_h2</span><span class="p">)))</span>
</pre></div>
</div>
</div>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[20]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">struct</span><span class="o">.</span><span class="n">get_positions</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[20]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>array([[  0.00000000e+00,   0.00000000e+00,   0.00000000e+00],
       [  0.00000000e+00,   0.00000000e+00,   1.07000000e+00],
       [  1.00880436e+00,  -1.11022302e-16,  -3.56660000e-01],
       [ -5.04400083e-01,   8.73653852e-01,  -3.56670000e-01],
       [ -5.04404280e-01,  -8.73653852e-01,  -3.56670000e-01]])
</pre></div>
</div>
</div>
<p>Exercise: Now compare the positions of the rotated structure with those of the new structure; you may want to compute the RMS difference.</p>
<p>Now change the cell and make a supercell</p>
</div>
<div class="section" id="Generating-structures-from-scratch">
<h2>Generating structures from scratch<a class="headerlink" href="#Generating-structures-from-scratch" title="Permalink to this headline">¶</a></h2>
<p>We could have also just used ASE functionality to pull a methane structure from its database:</p>
<div class="nbinput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[21]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="kn">import</span> <span class="nn">ase</span>
<span class="kn">from</span> <span class="nn">ase.build</span> <span class="kn">import</span> <span class="n">molecule</span>
</pre></div>
</div>
</div>
<div class="nbinput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[22]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">me</span> <span class="o">=</span> <span class="n">molecule</span><span class="p">(</span><span class="s1">&#39;CH4&#39;</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="nbinput docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[23]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span><span class="n">me</span><span class="o">.</span><span class="n">get_positions</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="nboutput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[23]:
</pre></div>
</div>
<div class="output_area highlight-none notranslate"><div class="highlight"><pre>
<span></span>array([[ 0.      ,  0.      ,  0.      ],
       [ 0.629118,  0.629118,  0.629118],
       [-0.629118, -0.629118,  0.629118],
       [ 0.629118, -0.629118, -0.629118],
       [-0.629118,  0.629118, -0.629118]])
</pre></div>
</div>
</div>
<p>Like the introductory tutorial at <a class="reference external" href="http://libatoms.github.io/QUIP/tutorial.html">http://libatoms.github.io/QUIP/tutorial.html</a> - use the <code class="docutils literal notranslate"><span class="pre">diamond</span></code> generator, view a supercell, do fun things with the structure…</p>
</div>
<div class="section" id="Computing-the-energy">
<h2>Computing the energy<a class="headerlink" href="#Computing-the-energy" title="Permalink to this headline">¶</a></h2>
<p>Introduce <code class="docutils literal notranslate"><span class="pre">Potential</span></code>. Use something like <code class="docutils literal notranslate"><span class="pre">IP</span> <span class="pre">SW</span></code> to get the energy of the silicon supercell. Direct user to the list of potentials and the next tutorial.</p>
<div class="nbinput nblast docutils container">
<div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[ ]:
</pre></div>
</div>
<div class="input_area highlight-ipython2 notranslate"><div class="highlight"><pre>
<span></span>
</pre></div>
</div>
</div>
</div>
</div>


           </div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="quippy-ase-interoperability.html" class="btn btn-neutral float-right" title="Interoperability with Atomic Simulation Environment" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="index.html" class="btn btn-neutral float-left" title="Tutorials" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2008-2016, James Kermode

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>